OpenEuphoria

open

<built-in> function open(sequence path, sequence mode, integer cleanup = 0) 

opens a file or device, to get the file number.

Parameters:

1. path : a string, the path to the file or device to open.
2. mode : a string, the mode being used o open the file.
3. cleanup : an integer, if 0, then the file must be manually closed by the coder. If 1, then the file will be closed when either the file handle's references goes to 0, or if called as a parameter to delete.

Returns:

A small integer, -1 on failure, else 0 or more.

Errors:

There is a limit on the number of files that can be simultaneously opened, currently 40. After this limit is reached the next call to open will produce an error.

The length of path should not exceed 1_024 characters.

Comments:

Possible modes are:

• "r" -- open text file for reading
• "rb" -- open binary file for reading
• "w" -- create text file for writing
• "wb" -- create binary file for writing
• "u" -- open text file for update (reading and writing)
• "ub" -- open binary file for update
• "a" -- open text file for appending
• "ab" -- open binary file for appending

Files opened for read or update must already exist. Files opened for write or append will be created if necessary. A file opened for write will be set to 0 bytes. Output to a file opened for append will start at the end of file.

On Windows, output to text files will have carriage-return characters automatically added before linefeed characters. On input, these carriage-return characters are removed. A Control+Z character (ASCII 26) will signal an immediate end of file.

I/O to binary files is not modified in any way. Any byte values from 0 to 255 can be read or written. On Unix, all files are binary files, so "r" mode and "rb" mode are equivalent, as are "w" and "wb", "u" and "ub", and "a" and "ab".

Some typical devices that you can open on Windows are:

• "CON" -- the console (screen)
• "AUX" -- the serial auxiliary port
• "COM1" -- serial port 1
• "COM2" -- serial port 2
• "PRN" -- the printer on the parallel port
• "NUL" -- a non-existent device that accepts and discards output

Close a file or device when done with it, flushing out any still-buffered characters prior.

Windows and Unix: Long filenames are fully supported for reading and writing and creating.

Windows: Be careful not to use the special device names in a file name, even if you add an extension. For example: CON.TXT, CON.DAT, CON.JPG all refer to the CON device and not to a file.

Example 1:

integer file_num, file_num95 
sequence first_line 
constant ERROR = 2 
 
file_num = open("my_file", "r") 
if file_num = -1 then 
    puts(ERROR, "couldn't open my_file\n") 
else 
    first_line = gets(file_num) 
end if 
 
file_num = open("PRN", "w") -- open printer for output 
 
-- on Windows 95: 
file_num95 = open("big_directory_name\\very_long_file_name.abcdefg", 
                  "r") 
if file_num95 != -1 then 
    puts(STDOUT, "it worked!\n") 
end if